<HTML><HEAD><TITLE>library(flatzinc)</TITLE></HEAD><BODY>
[ <A HREF="../../index.html">Reference Manual</A> | <A HREF="../../fullindex.html">Alphabetic Index</A> ]<H1>library(flatzinc)</H1>
Interpreter for FlatZinc
<H2>Predicates</H2>
<BLOCKQUOTE>
<DL>
<DT><STRONG>fzn_error(?, ?)</STRONG></DT>
<DD>No description available</DD>
<DT><A HREF="fzn_init-2.html"><STRONG>fzn_init(++SolverOrOptions, -FznState)</STRONG></A></DT>
<DD>Initialize a FlatZinc solver</DD>
<DT><A HREF="fzn_last-1.html"><STRONG>fzn_last(+FznState)</STRONG></A></DT>
<DD>Increments solutions count, and succeeds if last one reached</DD>
<DT><A HREF="fzn_load_stream-2.html"><STRONG>fzn_load_stream(+ModelStream, -FznState)</STRONG></A></DT>
<DD>Load a FlatZinc model and set up its constraints</DD>
<DT><A HREF="fzn_obj_lookup-2.html"><STRONG>fzn_obj_lookup(+FznState, -Obj)</STRONG></A></DT>
<DD>Find ECLiPSe term representing the Mini/FlatZinc model's objective</DD>
<DT><A HREF="fzn_output-1.html"><STRONG>fzn_output(+FznState)</STRONG></A></DT>
<DD>Perform a FlatZinc model's output actions</DD>
<DT><A HREF="fzn_run-1.html"><STRONG>fzn_run(+SolverOrOptions)</STRONG></A></DT>
<DD>Run a FlatZinc model from standard input</DD>
<DT><A HREF="fzn_run-2.html"><STRONG>fzn_run(+File, ++SolverOrOptions)</STRONG></A></DT>
<DD>Run a FlatZinc model from a given file</DD>
<DT><A HREF="fzn_run_stream-2.html"><STRONG>fzn_run_stream(+Stream, ++SolverOrOptions)</STRONG></A></DT>
<DD>Run a FlatZinc model from a given open input stream</DD>
<DT><A HREF="fzn_search-1.html"><STRONG>fzn_search(+FznState)</STRONG></A></DT>
<DD>Run the search part of a FlatZinc model</DD>
<DT><A HREF="fzn_var_lookup-3.html"><STRONG>fzn_var_lookup(+FznState, +Id, -Value)</STRONG></A></DT>
<DD>Find ECLiPSe term corresponding to Mini/FlatZinc identifier</DD>
<DT><STRONG>fzn_write(?, ?)</STRONG></DT>
<DD>No description available</DD>
<DT><STRONG>fzn_write(?, ?, ?, ?)</STRONG></DT>
<DD>No description available</DD>
<DT><STRONG>zn_options(?, ?)</STRONG></DT>
<DD>No description available</DD>
</DL>
</BLOCKQUOTE>
<H2>Structures</H2>
<BLOCKQUOTE>
<DL>
<DT><A HREF="zn_options-s.html"><STRONG>struct zn_options(solver, fzn_tmp, parser, setup_prio, solutions, var_names)</STRONG></A></DT>
<DD>Options for Mini/FlatZinc solving</DD>
<DT><A HREF="zn_var-s.html"><STRONG>struct zn_var(id, ann, type, group, eclvar, num)</STRONG></A></DT>
<DD>Descriptor for a Mini/FlatZinc variable</DD>
</DL>
</BLOCKQUOTE>
<H2>Description</H2>

<H3>
Overview
</H3>
<P>
The core of this module is an interpreter for FlatZinc models, based
on 'Specification of FlatZinc' (Nov 7 2007).  It uses
lib(flatzinc_parser) to read a FlatZinc model one item at a time, and
immediately interprets it.  The mapping from FlatZinc built-in
operations to actual ECLiPSe solver operations is in separate modules
called fzn_ic, fzn_fd, fzn_eplex, etc.
</P>

<H3>
Running FlatZinc Models
</H3>
<P>
If you have a file containing a FlatZinc model, it can be loaded and
executed from ECLiPSE by calling
<PRE>
    ?- fzn_run("model.fzn", fzn_ic).
</PRE>
where model.fzn is the file name and fzn_ic is the name of the chosen
solver mapping. It is also possible to read a model from the standard
input using fzn_run/1, or from an arbitrary ECLiPSe input stream using
fzn_run_stream/2.
</P>
If finer control is needed, the processing of a FlatZinc model can be
split up into initialization, loading and constraint-set-up, search,
and output.  The primitives that perform these steps are exported
and can be invoked separately, e.g.
<PRE>
my_fzn_run_stream(ModelStream, Options) :-

	% initialize the solver state
	fzn_init(Options, State),

	% load the model and set up the constraints
	fzn_load_stream(ModelStream, State),

	% perform the search
	fzn_search(State),

	% output solution, if found
	fzn_output(State).
</PRE>
</P>

<H3>
Creating FlatZinc Models
</H3>
<P>
Note that FlatZinc is not intended to be written by humans, but
created by translating models written in Zinc or MiniZinc.  A
translator for MiniZinc to FlatZinc called mzn2fzn is available at
<A HREF="http://www.g12.csse.unimelb.edu.au/minizinc">
http://www.g12.csse.unimelb.edu.au/minizinc</A>
</P>
<P>
The use of an intermediate FlatZinc file can be avoided by
piping the result of the MiniZinc to FlatZinc converter directly
into the ECLiPSe-FlatZinc interpreter, e.g. via
<PRE>
% mzn2fzn --output-to-stdout model.mzn | eclipse -e "flatzinc:fzn_run(fzn_ic)"
</PRE>
The file lib/fzn_ic/globals.mzn contains specialised global constraint
definitinions for the use of fzn_ic.
For alternative ways to run MiniZinc models, see library(minizinc).
</P>

<H3>
How to write a new solver mapping
</H3>
<P>
The mapping from FlatZinc built-in operations to actual ECLiPSe solver
operations is defined in separate modules called fzn_ic, fzn_eplex, etc. 
To add a new mapping, create a new module file called fzn_xxx.ecl, and
place it in your library_path.
These modules should export predicates corresponding to the "built-in"
operations defined by FlatZinc, i.e.
<CODE>
int_lin_le/3, float_times/3,
</CODE>
etc.  See the FlatZinc specification for a complete list.
</P><P>
In addition to those, we require the following interface predicates:
</P><P>
For initialising variables:
<CODE>
bool_declare(-var),
int_declare(-var),
int_declare(-var, +list),
int_declare(-var, +min, +max),
float_declare(-var),
float_declare(-var, +min, +max),
set_declare(-var, +min, +max),
set_declare(-var, +list)
</CODE>
</P><P>
For initialising arrays:
<CODE>
bool_declare_array(-array),
int_declare_array(-array),
int_declare_array(-array, +list),
int_declare_array(-array, +min, +max),
float_declare_array(-array),
float_declare_array(-array, +min, +max),
set_declare_array(-array, +min, +max),
set_declare_array(-array, +list)
</CODE>
</P><P>
For invoking search:
<CODE>
satisfy(+annotations),
minimize(+objective, +annotations, -cost),
maximize(+objective, +annotations, -cost)
</CODE>
</P><P>
For converting constants in the Zinc model to the appropriate solver
type in ECLiPSe (e.g. floats to breals when using lib(ic)):
<CODE>
bool_fzn_to_solver(+atom, -bool),
bool_solver_to_fzn(+bool, -atom),
float_fzn_to_solver(+float, -real),
float_solver_to_fzn(+real, -float),
set_fzn_to_solver(+list, -set),
set_solver_to_fzn(+set, -list),
range_fzn_to_solver(+min, +max, -set).
</CODE>
</P>
<P>
<H3>
Further Details
</H3>
By default, the 'output' primitive suppresses all variables with
the var_is_introduced annotation.
<H3>
TODO
</H3>
<UL>
<LI>interpret more variable annotations</LI>
<LI>constraint annotations (currently ignored)</LI>
<LI>stricter checking of the FlatZinc input?</LI>
</UL>
</P>

<H2>About</H2><UL COMPACT>
<LI><STRONG>Status: </STRONG>prototype
<LI><STRONG>Author: </STRONG>Joachim Schimpf, supported by Cisco Systems and NICTA Victoria
<LI><STRONG>Copyright &copy; </STRONG>Cisco Systems Inc, licensed under CMPL
<LI><STRONG>Date: </STRONG>$Date: 2009/03/26 08:15:18 $
</UL>
<H2>See Also</H2>
<A HREF="../../lib_public/minizinc/index.html">library(minizinc)</A>, <A HREF="../../lib_public/flatzinc_parser/index.html">library(flatzinc_parser)</A>, <A HREF="../../lib_public/fzn_ic/index.html">library(fzn_ic)</A>, <A HREF="../../lib_public/fzn_fd/index.html">library(fzn_fd)</A>, <A HREF="../../lib_public/fzn_eplex/index.html">library(fzn_eplex)</A><HR>Generated from flatzinc.eci on 2009-05-27 01:25
</BODY></HTML>
